---
title: PuckApi
---

import { Callout } from "nextra/components";

# PuckApi

`PuckApi` exposes Puck's internals to enable extension and modification to Puck's core behavior. It can be accessed by the [`usePuck`](/docs/api-reference/functions/use-puck) and [`useGetPuck`](/docs/api-reference/functions/use-get-puck) hooks.

<Callout type="info">
  `PuckApi` can currently only be accessed through
  [composition](/docs/extending-puck/composition), [UI
  overrides](/docs/extending-puck/ui-overrides) or [custom
  fields](/docs/extending-puck/custom-fields).
</Callout>

## Params

| Param                                             | Example                                            | Type                                                           |
| ------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
| [`appState`](#appstate)                           | `{ data: {}, ui: {} }`                             | [AppState](/docs/api-reference/data-model/app-state)           |
| [`dispatch`](#dispatchaction)                     | `(action: PuckAction) => void`                     | Function                                                       |
| [`getItemBySelector`](#getitembyselectorselector) | `() => ({ type: "Heading", props: {} })`           | Function                                                       |
| [`getItemById`](#getitembyidid)                   | `() => ({ type: "Heading", props: {} })`           | Function                                                       |
| [`getSelectorForId`](#getselectorforidid)         | `() => ({ index: 0, zone: 'Flex-123:children'  })` | Function                                                       |
| [`getPermissions`](#getpermissionsparams)         | `() => ({ delete: true  })`                        | Function                                                       |
| [`history`](#history)                             | `{}`                                               | Object                                                         |
| [`refreshPermissions`](#refreshpermissionsparams) | `() => void`                                       | Function                                                       |
| [`selectedItem`](#selecteditem)                   | `{ type: "Heading", props: {id: "my-heading"} }`   | [ComponentData](/docs/api-reference/data-model/data#content-1) |

### `appState`

The current [application state](/docs/api-reference/data-model/app-state) for this Puck instance.

```tsx
console.log(appState.data);
// { content: [], root: {}, zones: {} }
```

### `dispatch(action)`

Execute an [action](/docs/api-reference/actions) to mutate the Puck [application state](/docs/api-reference/data-model/app-state).

```tsx
dispatch({
  type: "setUi",
  ui: {
    leftSideBarVisible: false,
  },
});
```

### `getItemBySelector(selector)`

Get an item's [`ComponentData`](/docs/api-reference/data-model/component-data) by its [selector](/docs/api-reference/data-model/item-selector).

```tsx
getItemBySelector({
  index: 0,
  zone: "Flex-123:children", // The "children" slot field in the component with id "Flex-123"
});
// { type: "HeadingBlock", props: {} }
```

### `getItemById(id)`

Get an item's [`ComponentData`](/docs/api-reference/data-model/component-data) by its component id.

```tsx
getItemById("HeadingBlock-123");
// { type: "HeadingBlock", props: {} }
```

### `getParentById(id)`

Get an item's parent [`ComponentData`](/docs/api-reference/data-model/component-data) using the child component's ID.

### `getSelectorForId(id)`

Get an item's [selector](/docs/api-reference/data-model/app-state#uiitemselector) by its component id.

```tsx
getSelectorForId("HeadingBlock-123");
// { index: 0, zone: "Flex-123:children" }
```

### `getPermissions(params)`

Get global, component or resolved dynamic [permissions](/docs/api-reference/permissions).

```tsx
getPermissions();
// { delete: true, edit: true }
```

#### Params

| Param  | Example                                           | Type    |
| ------ | ------------------------------------------------- | ------- |
| `item` | `{ type: "HeadingBlock", props: { id: "1234" } }` | Object  |
| `root` | `false`                                           | Boolean |
| `type` | `"HeadingBlock"`                                  | String  |

##### `item`

Specify `item` to retrieve the permissions for a given component instance, resolving any dynamic permissions for that component, as set by the [`resolvePermissions` parameter](/docs/api-reference/configuration/component-config#resolvepermissionsdata-params).

```tsx
getPermissions({
  item: { type: "HeadingBlock", props: { id: "Heading-1234" } }, // Get resolved permissions for Heading-1234
});
// { delete: false }
```

The `getPermissions` function will be redefined when after resolving dynamic permissions, so it's generally required to wrap it in a `useEffect` hook:

```tsx
const [myPermissions, setMyPermissions] = useState(getPermissions());

useEffect(() => {
  setMyPermissions(getPermissions());
}, [getPermissions]);
```

##### `root`

Specify `root` to retrieve the permissions for the `root`, as set by the [`permissions` parameter](/docs/api-reference/configuration/component-config#permissions).

```tsx
getPermissions({ root: true });
// { delete: false }
```

##### `type`

Specify `type` to retrieve the permissions for a given component type, as set by the [`permissions` parameter](/docs/api-reference/configuration/component-config#permissions).

```tsx
getPermissions({ type: "HeadingBlock" });
// { delete: false }
```

### `history`

The `history` API provides programmatic access to the undo/redo [AppState](/docs/api-reference/data-model/app-state) history.

| Param                                 | Example                             | Type                           |
| ------------------------------------- | ----------------------------------- | ------------------------------ |
| [`back`](#historyback)                | `() => void`                        | Function                       |
| [`forward`](#historyforward)          | `() => void`                        | Function                       |
| [`hasPast`](#historyhaspast)          | `true`                              | Boolean                        |
| [`hasFuture`](#historyhasfuture)      | `false`                             | Boolean                        |
| [`histories`](#historyhistories)      | `[{ id: 'abc123', data: {} }]`      | [History](#history-params)\[\] |
| [`index`](#historyindex)              | `5`                                 | Number                         |
| [`setHistories`](#sethistories)       | `setHistories: (histories) => void` | Function                       |
| [`setHistoryIndex`](#sethistoryindex) | `setHistoryIndex: (index) => void`  | Function                       |

#### `history.back()`

A function to move the app state back through the [histories](#historyhistories).

#### `history.forward()`

A function to move the app state forward through the [histories](#historyhistories).

#### `history.hasPast`

A boolean describing whether or not the present app state has past history items.

#### `history.hasFuture`

A boolean describing whether or not the present app state has future history items.

#### `history.histories`

An array describing the recorded history as `History` objects.

##### `History` params

| Param   | Example  | Type                                                 |
| ------- | -------- | ---------------------------------------------------- |
| `state` | `{}`     | [AppState](/docs/api-reference/data-model/app-state) |
| `id`    | `abc123` | String                                               |

###### `state`

The [app state](/docs/api-reference/data-model/app-state) payload for this history entry.

###### `id`

An optional ID for this history entry.

#### `history.index`

The index of the currently selected history in [`history.histories`](#historyhistories)

#### `setHistories`

A function to set the history state.

```tsx
setHistories([]); // clears all history
```

#### `setHistoryIndex`

A function to set current history index.

```tsx
setHistoryIndex(2);
```

### `refreshPermissions(params)`

Force the permissions to refresh, running all [`resolvePermissions` functions](/docs/api-reference/configuration/component-config#resolvepermissionsdata-params) and skipping the cache.

```tsx
resolvePermissions(); // Refresh all permissions
```

#### Params

| Param  | Example                                           | Type    |
| ------ | ------------------------------------------------- | ------- |
| `item` | `{ type: "HeadingBlock", props: { id: "1234" } }` | Object  |
| `root` | `false`                                           | Boolean |
| `type` | `"HeadingBlock"`                                  | String  |

##### `item`

Specify `item` to refresh the permissions for a given component instance only.

```tsx
refreshPermissions({
  item: { type: "HeadingBlock", props: { id: "Heading-1234" } }, // Force refresh the resolved permissions for Heading-1234
});
```

##### `root`

Specify `root` to refresh the permissions for the `root` only.

```tsx
refreshPermissions({ root: true });
```

##### `type`

Specify `type` to refresh the permissions for all components of a given component type.

```tsx
refreshPermissions({ type: "HeadingBlock" });
```

### `selectedItem`

The currently selected item, as defined by `appState.ui.itemSelector`.

```tsx
console.log(selectedItem);
// { type: "Heading", props: {id: "my-heading"} }
```
